前情提要

因應近期技術更新飛快，得益於各大語言模型和 Vibe Coding 所帶來的便利的同時，愈發覺得需要一個地方整理 & 釐清思路而不是完全依賴這些生成式模型的產出，思來想去還是決定重拾從前記筆記的習慣。因為 Obsidian 是自己最習慣的筆記軟體，加上偶然發現一篇將 Obsidian.md 轉為靜態網頁的文章，於是這個計畫就此誕生。

檔案結構

Obsidian 工作區的檔案結構如下：

├── Workspace/
│ └── Folder/
│ │ └── Page.md
│ └── .obsidian
│ └── index.md

在此結構外加上一層資料夾，將與筆記無關的檔案存放於該位置：

. 
├── docs/ 
│ └── .obsidian
│ └── index.md
├── .gitlab-ci.yml
├── mkdocs.yml
└── requirements.txt

• docs/ - 也就是原先的工作區
• .obsidian - 存放既有的 Obsidian 設定檔
• index.md - MkDocs 會查找工作區內的 index.md 作為靜態網頁的主頁
• .gitlab-ci.yml - GitLab CI 設定檔
• mkdocs.yml - MkDocs 設定檔
• requirements.txt - MkDocs 所需要的 Python 套件

基本 MkDocs 設置

使用 YAML 配置專案設定，基本設定如下：

site_name: My Obsidian Notes
site_url: https://group-name.gitlab.io/repo-name
site_dir: public
docs_dir: ./docs

• site_name- 將作為網站的主要標題
• site_url- 這邊使用 GitLab Pages 提供的預設 URL 或自有的網域
• site_dir- MkDocs 生成檔案放置的資料夾，同時也是 GitLab Pages 的預設資料夾
• docs_dir- 指向工作區的相對路徑

安裝 Python 套件

使用 requirements.txt 存放必要的 Python 套件

# Documentation static site generator & deployment tool
mkdocs==1.6.1

如此一來不論本地或是腳本都能透過 pip install -r requirements.txt 安裝

客製樣式

如果想要進一步設定靜態網站樣式，除了 Mkdocs 預設的兩種樣式外，還有不少社群開發的主題可供選用。這邊使用和原作者相同的 Material 作為主題。需留意 YAML 檔的換行可能造成建置失敗，另外目前尚未找到支援 block reference 的套件實屬可惜！

配置 GitLab CI

於 .gitlab-ci.yml 設定發布靜態網頁流程：

image: python:3.11-slim

pages:
  stage: deploy
  script:
    # Install all of the python packages for mkdocs
    - pip install -r requirements.txt
    # Build the site using mkdocs
    # --strict aborts the build on any warnings
    # --verbose enables verbose output so that it's easier to see what mkdocs is doing
    # neither --strict nor --verbose are necessary if you choose not to use them
    - mkdocs build --strict --verbose
  artifacts:
    paths:
      - public
  only:
    - main

---

參考資料

• Publishing Obsidian.md notes with GitLab Pages